Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Enable API documentation for std::os::wasi. #82420

Merged
merged 6 commits into from
Feb 27, 2021

Conversation

sunfishcode
Copy link
Member

This adds API documentation support for std::os::wasi modeled after
how std::os::unix works, so that WASI can be documented here along
with the other platforms.

Two changes of particular interest:

  • This changes the AsRawFd for io::Stdin for WASI to return
    libc::STDIN_FILENO instead of sys::stdio::Stdin.as_raw_fd() (and
    similar for Stdout and Stderr), which matches how the unix
    version works. STDIN_FILENO etc. may not always be explicitly
    reserved at the WASI level, but as long as we have Rust's std and
    libc, I think it's reasonable to guarantee that we'll always use
    libc::STDIN_FILENO for stdin.

  • This duplicates the osstr2str utility function, rather than
    trying to share it across all the configurations that need it.

r? @alexcrichton

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Feb 22, 2021
@alexcrichton
Copy link
Member

@bors: r+

@bors
Copy link
Contributor

bors commented Feb 22, 2021

📌 Commit 643d2ce3e2de481593bc4aaee81f1df361680864 has been approved by alexcrichton

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Feb 22, 2021
library/std/src/os/mod.rs Outdated Show resolved Hide resolved
@camelid camelid added O-wasm Target: WASM (WebAssembly), http://webassembly.org/ A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools T-libs-api Relevant to the library API team, which will review and decide on the PR/issue. labels Feb 23, 2021
@bors
Copy link
Contributor

bors commented Feb 23, 2021

☔ The latest upstream changes (presumably #82430) made this pull request unmergeable. Please resolve the merge conflicts.

@bors bors added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Feb 23, 2021
@rust-log-analyzer

This comment has been minimized.

This adds API documentation support for `std::os::wasi` modeled after
how `std::os::unix` works, so that WASI can be documented [here] along
with the other platforms.

[here]: https://doc.rust-lang.org/stable/std/os/index.html

Two changes of particular interest:

 - This changes the `AsRawFd` for `io::Stdin` for WASI to return
   `libc::STDIN_FILENO` instead of `sys::stdio::Stdin.as_raw_fd()` (and
   similar for `Stdout` and `Stderr`), which matches how the `unix`
   version works. `STDIN_FILENO` etc. may not always be explicitly
   reserved at the WASI level, but as long as we have Rust's `std` and
   `libc`, I think it's reasonable to guarantee that we'll always use
   `libc::STDIN_FILENO` for stdin.

 - This duplicates the `osstr2str` utility function, rather than
   trying to share it across all the configurations that need it.
@alexcrichton
Copy link
Member

@bors: r+ delegate+

@bors
Copy link
Contributor

bors commented Feb 23, 2021

📌 Commit 132ec26 has been approved by alexcrichton

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Feb 23, 2021
@bors
Copy link
Contributor

bors commented Feb 23, 2021

✌️ @sunfishcode can now approve this pull request

@CDirkx
Copy link
Contributor

CDirkx commented Feb 23, 2021

Currently the documentation does not build for all platforms:

pub mod prelude {
#[doc(no_inline)]
#[stable(feature = "rust1", since = "1.0.0")]
pub use crate::sys::ext::ffi::{OsStrExt, OsStringExt};
#[doc(no_inline)]
#[stable(feature = "rust1", since = "1.0.0")]
pub use crate::sys::ext::fs::FileTypeExt;
#[doc(no_inline)]
#[stable(feature = "rust1", since = "1.0.0")]
pub use crate::sys::ext::fs::{DirEntryExt, FileExt, MetadataExt, OpenOptionsExt};
#[doc(no_inline)]
#[stable(feature = "rust1", since = "1.0.0")]
pub use crate::sys::ext::io::{AsRawFd, FromRawFd, IntoRawFd, RawFd};
}

All these should use super:: instead of crate::sys::ext because with this change, when documenting on windows for example, sys::ext will be the windows ext, not the wasi one.

Also, technically if one would ever document targeting wasi (not currently possible I think) the module os::wasi would be defined twice because of the missing #[cfg(not(doc))]:

#[cfg(target_os = "wasi")]
pub mod wasi;

and now wasi can also be added to the comment at the top of os/mod.rs:

// When documenting libstd we want to show unix/windows/linux modules as these are the "main

@CDirkx
Copy link
Contributor

CDirkx commented Feb 23, 2021

Capture

Rustdoc will also need to be updated, but that can be a followup.

Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this pull request Feb 24, 2021
Enable API documentation for `std::os::wasi`.

This adds API documentation support for `std::os::wasi` modeled after
how `std::os::unix` works, so that WASI can be documented [here] along
with the other platforms.

[here]: https://doc.rust-lang.org/stable/std/os/index.html

Two changes of particular interest:

 - This changes the `AsRawFd` for `io::Stdin` for WASI to return
   `libc::STDIN_FILENO` instead of `sys::stdio::Stdin.as_raw_fd()` (and
   similar for `Stdout` and `Stderr`), which matches how the `unix`
   version works. `STDIN_FILENO` etc. may not always be explicitly
   reserved at the WASI level, but as long as we have Rust's `std` and
   `libc`, I think it's reasonable to guarantee that we'll always use
   `libc::STDIN_FILENO` for stdin.

 - This duplicates the `osstr2str` utility function, rather than
   trying to share it across all the configurations that need it.

r? `@alexcrichton`
Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this pull request Feb 24, 2021
Enable API documentation for `std::os::wasi`.

This adds API documentation support for `std::os::wasi` modeled after
how `std::os::unix` works, so that WASI can be documented [here] along
with the other platforms.

[here]: https://doc.rust-lang.org/stable/std/os/index.html

Two changes of particular interest:

 - This changes the `AsRawFd` for `io::Stdin` for WASI to return
   `libc::STDIN_FILENO` instead of `sys::stdio::Stdin.as_raw_fd()` (and
   similar for `Stdout` and `Stderr`), which matches how the `unix`
   version works. `STDIN_FILENO` etc. may not always be explicitly
   reserved at the WASI level, but as long as we have Rust's `std` and
   `libc`, I think it's reasonable to guarantee that we'll always use
   `libc::STDIN_FILENO` for stdin.

 - This duplicates the `osstr2str` utility function, rather than
   trying to share it across all the configurations that need it.

r? ``@alexcrichton``
@JohnTitor
Copy link
Member

Failed in rollup: #82472 (comment)
@bors r-

@bors bors added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Feb 24, 2021
WASI's `RawFd` is a `u32`, while `libc` uses `c_int`.
This ensures that these names resolve to the right place even when
building the WASI support on other platforms for generating the
documentation.
@sunfishcode
Copy link
Member Author

Thanks! I've now fixed the crate::sys::ext paths, added the cfg(not(doc)) to the main wasi module, and added "wasi" to the "main module" comment.

@alexcrichton
Copy link
Member

@bors: r+

@bors
Copy link
Contributor

bors commented Feb 25, 2021

📌 Commit 7d5242a has been approved by alexcrichton

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Feb 25, 2021
Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this pull request Feb 26, 2021
Enable API documentation for `std::os::wasi`.

This adds API documentation support for `std::os::wasi` modeled after
how `std::os::unix` works, so that WASI can be documented [here] along
with the other platforms.

[here]: https://doc.rust-lang.org/stable/std/os/index.html

Two changes of particular interest:

 - This changes the `AsRawFd` for `io::Stdin` for WASI to return
   `libc::STDIN_FILENO` instead of `sys::stdio::Stdin.as_raw_fd()` (and
   similar for `Stdout` and `Stderr`), which matches how the `unix`
   version works. `STDIN_FILENO` etc. may not always be explicitly
   reserved at the WASI level, but as long as we have Rust's `std` and
   `libc`, I think it's reasonable to guarantee that we'll always use
   `libc::STDIN_FILENO` for stdin.

 - This duplicates the `osstr2str` utility function, rather than
   trying to share it across all the configurations that need it.

r? `@alexcrichton`
Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this pull request Feb 27, 2021
Enable API documentation for `std::os::wasi`.

This adds API documentation support for `std::os::wasi` modeled after
how `std::os::unix` works, so that WASI can be documented [here] along
with the other platforms.

[here]: https://doc.rust-lang.org/stable/std/os/index.html

Two changes of particular interest:

 - This changes the `AsRawFd` for `io::Stdin` for WASI to return
   `libc::STDIN_FILENO` instead of `sys::stdio::Stdin.as_raw_fd()` (and
   similar for `Stdout` and `Stderr`), which matches how the `unix`
   version works. `STDIN_FILENO` etc. may not always be explicitly
   reserved at the WASI level, but as long as we have Rust's `std` and
   `libc`, I think it's reasonable to guarantee that we'll always use
   `libc::STDIN_FILENO` for stdin.

 - This duplicates the `osstr2str` utility function, rather than
   trying to share it across all the configurations that need it.

r? ``@alexcrichton``
bors added a commit to rust-lang-ci/rust that referenced this pull request Feb 27, 2021
Rollup of 14 pull requests

Successful merges:

 - rust-lang#81794 (update tracking issue for `relaxed_struct_unsize`)
 - rust-lang#82057 (Replace const_cstr with cstr crate)
 - rust-lang#82370 (Improve anonymous lifetime note to indicate the target span)
 - rust-lang#82394 (:arrow_up: rust-analyzer)
 - rust-lang#82396 (Add Future trait for doc_spotlight feature doc)
 - rust-lang#82404 (Test hexagon-enum only when llvm target is present)
 - rust-lang#82419 (expand: Preserve order of inert attributes during expansion)
 - rust-lang#82420 (Enable API documentation for `std::os::wasi`.)
 - rust-lang#82421 (Add a `size()` function to WASI's `MetadataExt`.)
 - rust-lang#82442 (Skip emitting closure diagnostic when closure_kind_origins has no entry)
 - rust-lang#82473 (Use libc::accept4 on Android instead of raw syscall.)
 - rust-lang#82482 (Use small hash set in `mir_inliner_callees`)
 - rust-lang#82490 (Update cargo)
 - rust-lang#82494 (Substitute erased lifetimes on bad placeholder type)

Failed merges:

 - rust-lang#82448 (Combine HasAttrs and HasTokens into AstLike)

r? `@ghost`
`@rustbot` modify labels: rollup
@bors bors merged commit f5b68a4 into rust-lang:master Feb 27, 2021
@rustbot rustbot added this to the 1.52.0 milestone Feb 27, 2021
@sunfishcode sunfishcode deleted the wasi-docs branch February 27, 2021 15:30
sunfishcode added a commit to sunfishcode/rust that referenced this pull request Feb 27, 2021
As a followup to [this comment] in rust-lang#82420, this patch teaches rustdoc
how to display WASI.

[this comment]: rust-lang#82420 (comment)
JohnTitor added a commit to JohnTitor/rust that referenced this pull request Mar 2, 2021
Teach rustdoc how to display WASI.

As a followup to [this comment] in rust-lang#82420, this patch teaches rustdoc
how to display WASI.

[this comment]: rust-lang#82420 (comment)

r? `@alexcrichton`
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools O-wasm Target: WASM (WebAssembly), http://webassembly.org/ S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-libs-api Relevant to the library API team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

9 participants